App Management
3.4.6The App Management API provides a way to manage io.Connect Browser apps. It offers abstractions for:
Application - a web app as a logical entity, registered in io.Connect Browser with some metadata (name, title, version, etc.) and with all the configuration needed to spawn one or more instances of it. The App Management API provides facilities for retrieving app metadata and for detecting when an application has been started;
Instance - a running copy of an app. The App Management API provides facilities for starting/stopping app instances and tracking app and instance related events;
The App Management API is accessible through the io.appManager
object.
APIobject
Description
Application Management API.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
inMemory | InMemory | An object, through which applications definitions stored in-memory can be programmatically imported or removed. |
||
myInstance | Instance | The instance of the application. |
Methods
applicationmethod
Signature
(name: string) => Application
Description
Returns an application by name.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | Name of the desired application. |
applicationsmethod
instancesmethod
onAppAddedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an application is registered in the environment. Replays the already added applications.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (app: Application) => any | Callback function to handle the event. Receives the added application as a parameter. |
onAppChangedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when the configuration for an application has changed.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (app: Application) => any | Callback function to handle the event. Receives the changed application as a parameter. |
onAppRemovedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when the application is removed from the environment.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (app: Application) => any | Callback function to handle the event. Receives the removed application as a parameter. |
onInstanceStartedmethod
Signature
(callback: (instance: Instance) => any) => UnsubscribeFunction
Description
Notifies when a new application instance has been started. Replays the already started instances.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (instance: Instance) => any | Callback function to handle the event. Receives the started application instance as a parameter. |
onInstanceStoppedmethod
Signature
(callback: (instance: Instance) => any) => UnsubscribeFunction
Description
Notifies when an application instance has been stopped.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (instance: Instance) => any | Callback function to handle the event. Receives the stopped application instance as a parameter. |
Applicationobject
Description
Object describing an app.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
caption | string | Application caption. |
||
icon | string | Application icon. |
||
instances | Instance[] | Instances of that app. |
||
name | string | Application name. |
||
title | string | Application title. |
||
userProperties | PropertiesObject | Generic object for passing properties, settings, etc., in the for of key/value pairs. |
||
version | string | Application version. |
Methods
onInstanceStartedmethod
Signature
(callback: (instance: Instance) => any) => UnsubscribeFunction
Description
Subscribes for the event which fires when an application instance is started.
Note: unlike the API's onInstanceStarted()
the Application's onInstanceStarted()
method doesn't replay the already started instances.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (instance: Instance) => any | Callback function to handle the newly started instance. |
onInstanceStoppedmethod
startmethod
Signature
(context?: object, options?: ApplicationStartOptions) => Promise<Instance>
Description
Returns the newly started application instance.
Parameters
Name | Type | Required | Description |
---|---|---|---|
context | object | The initial context of the application. |
|
options | ApplicationStartOptions | Options object in which you can specify window setting (that will override the default configuration settings), as well as other additional options. |
ApplicationStartOptionsobject
Description
Object with options for starting an application.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
channelId | string | Name of the Channel which the window will join. |
||
height | number | 400 | Window height. |
|
left | number | 0 | Distance of the top left window corner from the left edge of the screen. |
|
relativeDirection | RelativeDirection | "right" | Direction ( |
|
relativeTo | string | The ID of the window that will be used to relatively position the new window.
Can be combined with |
||
top | number | 0 | Distance of the top left window corner from the top edge of the screen. |
|
waitForAGMReady | boolean | |||
width | number | 400 | Window width. |
ChannelSelectorobject
Description
Settings for the Channel Selector displayed on an io.Connect Window.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
enabled | boolean | If |
Definitionobject
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
caption | string | Application caption. |
||
customProperties | PropertiesObject | Generic object for passing properties, settings, etc., in the for of key/value pairs. Accessed using the app.userProperties property. |
||
details | DefinitionDetails | Detailed configuration. |
||
fdc3 | FDC3DefinitionV2 | The FDC3 2.0 version of the definition. If set, this means the current definition was imported as FDC3 2.0 and parsed to IOConnectBrowser one. |
||
hidden | boolean | If set to true, the application will not be listed in the io.Connect Browser Launchpad. Defaults to false. |
||
icon | string | Application icon. |
||
intents | Intent[] | The list of intents implemented by the Application |
||
name | string | Application name. Should be unique. |
||
title | string | The title of the app. Sets the window's title. |
||
type | string | Type of the application - the only supported type in io.Connect Browser is "window". More complex types are available in io.Connect Desktop. |
||
version | string | Application version. |
DefinitionDetailsobject
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
channelSelector | ChannelSelector | Settings for the Channel Selector displayed on an io.Connect Window. |
||
height | number | 400 | Window height. |
|
iframePermissionsPolicy | IFramePermissionsPolicyConfig | Configuration for the |
||
left | number | 0 | Distance of the top left window corner from the left edge of the screen. |
|
top | number | 0 | Distance of the top left window corner from the top edge of the screen. |
|
url | string | |||
width | number | 400 | Window width. |
|
workspacesSandbox | WorkspacesSandbox | Configuration for the |
FDC3DefinitionV1object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
appId | string | The unique application identifier located within a specific application directory instance. |
||
contactEmail | string | Optional e - mail to receive queries about the application. |
||
customConfig | PropertiesObject | An optional set of name value pairs that can be used to deliver custom data from an App Directory to a launcher. |
||
description | string | Description of the application.This will typically be a 1 - 2 paragraph style blurb about the application.Allow mark up language. |
||
icons | IconV1[] | Holds Icons used for the application, a Launcher may be able to use multiple Icon sizes or there may be a 'button' Icon. |
||
images | ImageV1[] | Array of images to show the user when they are looking at app description.Each image can have an optional description / tooltip. |
||
intents | Intent[] | The list of intents implemented by the Application |
||
manifest | string | URI or full JSON of the application manifest providing all details related to launch and use requirements as described by the vendor. The format of this manifest is vendor specific, but can be identified by the manifestType attribute. |
||
manifestType | string | The manifest type which relates to the format and structure of the manifest content. The definition is based on the vendor specific format and definition outside of this specification. |
||
name | string | Application name. Should be unique. |
||
publisher | string | The name of the company that owns the application.The publisher has control over their namespace / app / signature. |
||
supportEmail | string | Optional e - mail to receive support requests for the application. |
||
title | string | The title of the application. Sets the window's title. |
||
tooltip | string | Optional tooltip description e.g. for a launcher. |
||
version | string | Application version. |
FDC3DefinitionV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
appId | string | The unique application identifier located within a specific application directory instance. |
||
categories | string[] | An array of string categories that describe the application. These are meant as a hint to catalogs or stores listing FDC3-enabled apps and it is expected that these will make a best effort to find appropriate categories (or category) under which to list the app. |
||
contactEmail | string | Optional e-mail to receive queries about the application |
||
customConfig | PropertiesObject[] | An optional set of name value pairs that can be used to deliver custom data from an App Directory to a launcher |
||
description | string | Description of the application. This will typically be a 1-2 paragraph style blurb about the application. |
||
details | { url: string; } | The type specific launch details of the application. These details are intended to be vendor-agnostic and MAY be duplicated or overridden by details provided in the hostManifests object for a specific host. |
||
hostManifests | any | A mapping from host name to a host-specific application manifest object or URI from which that manifest can be retrieved. The manifest should provide details required to launch and use the application within the specified host. The manifest MAY duplicate or override information provided in the details field. |
||
icons | IconV2[] | Holds Icons used for the application, a Launcher may be able to use multiple Icon sizes or there may be a 'button' Icon |
||
interop | InteropV2 | Metadata that describes how the application uses FDC3 APIs. This metadata serves multiple purposes:
|
||
lang | string | A language tag that specifies the primary language of both the application and its AppD entry, as defined by IETF RFC 5646. |
||
localizedVersions | { [languageTag: string]: LocalizedVersionDefinition; } | Provides localized alternatives to any field of the AppD record, which may also refer to an alternative version of the application that is also localized (e.g. by providing an alternative URL). The keys to this object should be language tags as defined by IETF RFC 5646, e.g. en, en-GB or fr-FR. |
||
moreInfo | string | Optional URL that provides more information about the application |
||
name | string | The name of the application. The name should be unique within an FDC3 App Directory instance. The exception to the uniqueness constraint is that an App Directory can hold definitions for multiple versions of the same app. The same appName could occur in other directories. We are not currently specifying app name conventions in the document. |
||
publisher | string | The name of the company that owns the application. The publisher has control over their namespace/app/signature. |
||
screenshots | ImageV2[] | Array of images to show the user when they are looking at app description. Each image can have an optional description/tooltip |
||
supportEmail | string | Optional e-mail to receive support requests for the application |
||
title | string | Optional title for the application, if missing use appName, typically used in a launcher UI. |
||
tooltip | string | Optional tooltip description e.g. for a launcher |
||
type | FDC3DefinitionV2Types | Enum: "web" "native" "citrix" "onlineNative" "other". The technology type that is used to launch and run the application. Each application type implies a particular set of launch details |
||
version | string | Version of the application. This allows multiple app versions to be defined using the same app name. This can be a triplet but can also include things like 1.2.5 (BETA) |
IconV1object
Description
Icon holder
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
icon | string | Icon URL. |
IconV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
size | string | |||
src | string | |||
type | string |
IFramePermissionsPolicyConfigobject
Description
Configuration for the allow
attribute of the <iframe>
element in which the app will be started when opened in a Workspace.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
flags | string | Collection of flags that will be applied to the |
ImageV1object
Description
App Image holder
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
url | string | App Image URL. |
ImageV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
label | string | |||
size | string | |||
src | string | |||
type | string |
ImportResultobject
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
errors | { app: string; error: string; }[] | A list of application names and errors of all the unsuccessful imports |
||
imported | string[] | A list of names of the successfully imported application definitions |
InMemoryobject
Description
An object, through which applications definitions stored in-memory can be programmatically imported or removed.
Methods
clearmethod
Signature
() => Promise<void>
Description
Removes all applications from the memory
exportmethod
Signature
() => Promise<(Definition | FDC3DefinitionV2 | FDC3DefinitionV1)[]>
Description
Exports all known application definitions
importmethod
Signature
(definitions: (Definition | FDC3DefinitionV2 | FDC3DefinitionV1)[], mode?: "replace" | "merge") => Promise<ImportResult>
Description
Imports the provided collection of application definitions. Returns an import result object, which contains the names of the successfully imported apps and a list of errors if any.
Parameters
Name | Type | Required | Description |
---|---|---|---|
definitions | (Definition | FDC3DefinitionV2 | FDC3DefinitionV1)[] | A collection of application definition objects to be imported. |
|
mode | "replace" | "merge" | Import mode, by default it is "replace". "replace" mode replaces all existing definitions with the provided collection, "merge" mode adds (if new) or updates (if already existing) the provided definitions. |
removemethod
Signature
(name: string) => Promise<void>
Description
Removed an application definition. This method will fire onAppRemoved if a definition was removed and it will do nothing if an app with this was was not found.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | The name of the definition to be removed. |
Instanceobject
Description
Object describing an application instance.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
agm | Instance | Interop instance. Use this to invoke Interop methods for that instance. |
||
application | Application | |||
id | string | Instance ID. |
Methods
getContextmethod
Signature
() => Promise<object>
Description
The starting context of the instance.
stopmethod
Signature
() => Promise<void>
Description
Stops the instance.
Intentobject
Description
An intent definition.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
contexts | string[] | A comma separated list of the types of contexts the intent offered by the application can process, here the first part of the context type is the namespace e.g."fdc3.contact, org.symphony.contact". |
||
customConfig | object | Custom configuration for the intent that may be required for a particular desktop agent. |
||
displayName | string | An optional display name for the intent that may be used in UI instead of the name. |
||
name | string | The name of the intent to 'launch'. In this case the name of an Intent supported by an Application. |
||
resultType | string | Result type may be a type name, the string "channel" (which indicates that the app will return a channel) or a string indicating a channel that returns a specific type, e.g. "channel<fdc3.instrument>" |
InteropAppChannelV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
broadcasts | string[] | |||
description | string | |||
listensFor | string[] | |||
name | string |
InteropIntentsV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
listensFor | { [intentName: string]: Pick<Intent, "displayName" | "contexts" | "customConfig" | "resultType">; } | |||
raises | { [intentName: string]: string[]; } |
InteropUserChannelV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
broadcasts | string[] | |||
listensFor | string[] |
InteropV2object
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
appChannels | InteropAppChannelV2[] | |||
intents | InteropIntentsV2 | |||
userChannels | InteropUserChannelV2 |
LocalizedVersionDefinitionobject
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
appId | string | |||
categories | string[] | |||
contactEmail | string | |||
customConfig | PropertiesObject[] | |||
description | string | |||
details | { url: string; } | |||
hostManifests | any | |||
icons | IconV2[] | |||
interop | InteropV2 | |||
lang | string | |||
localizedVersions | { [languageTag: string]: LocalizedVersionDefinition; } | |||
moreInfo | string | |||
name | string | |||
publisher | string | |||
screenshots | ImageV2[] | |||
supportEmail | string | |||
title | string | |||
tooltip | string | |||
type | FDC3DefinitionV2Types | |||
version | string |
PropertiesObjectobject
Description
Generic object for passing properties, settings, etc., in the for of key/value pairs.
WorkspacesSandboxobject
Description
Configuration for the sandbox
attribute of the <iframe>
element in which the app will be started when opened in a Workspace.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
flags | string | Collection of flags that will be applied to the |
FDC3DefinitionV2Typesenumeration
Description
- "web"
- "native"
- "citrix"
- "onlineNative"
- "other"